Super PC 34

home *** CD-ROM | disk | FTP | other *** search

/ Super PC 34 / Super PC 34 (Shareware).iso / spc / UTIL / FASTCD09 / TBONES07 / TBONES07.DOC < prev next >

Wrap

Text File | 1991-01-20 | 17.7 KB | 405 lines

*************************************************************************** * * * T-BONES * * Version 0.7 * * January 20, 1991 * * * * SKELETAL ASM PROGRAMS TO HELP IN PROGRAMMING YOUR OWN TSRs * * * * Copyright (C) 1990, 1991 by Robert Curtis Davis * * * * Internet E-mail address: sonny@trantor.harris-atd.com * * * * US Mail: 430 Bahama Drive * * Indialantic, FL 32903 * * * *************************************************************************** ONE-LINE DESCRIPTION: -------------------- TBONESxx.ZIP - Skeletal ASM programs for your own TSRs. *************************************************************************** DISCLAIMER: ---------- T-BONES is currently under development and this is a preliminary version. This software is not warranted to be suitable for any purpose and the author will not be held responsible for any damages arising directly or indirectly from its use. By the act of using this software, the user agrees to these conditions. *************************************************************************** DESCRIPTION: ----------- T-BONES is a set of skeletal Assembly Language programs which can be used as starting points in developing Terminate-but-Stay- Resident (TSR) programs for your DOS computer. BACKGROUND: ---------- In examining some software packages useful in learning about TSRs, I couldn't seem to find one that provided skeletal ASM programs into which I could easily drop my own Interrupt-triggered or Hot Key-triggered routines. It was toward the provision of these bare-bones programs which had already taken care of all the various details (initialization, saving old interrupt vectors, installing new interrupt vectors, going resident, determining if DOS code was interrupted, determining if DOS is at "Busy idle", determining if the TSR is already installed, etc.) necessary in some TSRs, that I undertook the writing of the programs in T-BONES as an aid to my own TSR programming efforts. Also, I recognized that not all the features enumerated are necessary in every TSR. For example, if you are not going to use DOS calls in your routine, checking to be sure DOS is at idle may be unnecessary. Therefore, I have included TSRINT and TSRKEY which are very simple and leave it up to you to stay out of DOS's way. Anyway, it is my hope, based upon feedback from users, to provide a set of useful skeletal TSR Assembly Language programs that make it relatively easy for programmers to drop their own routines into place without having to start all over from scratch on every TSR. ------------------------------------------ PERMITTED DISTRIBUTION AND USAGE OF TBONES: No current restrictions are placed on the distribution either of the TBONES package itself (please pass it on to anyone who might use it) or on TSRs you might develop using this TBONES software package. But please leave somewhere in your program an acknowledgement of TBONES' help in making the TSR. Other than that, feel free to modify the ASM file (filename, comments, output messages, TSR signature, etc.) to make it "look" and "feel" as you wish. ------------------------------------------ TBONES' COST: I presently ask only that you send me (preferably by E-mail) a free copy of any generally-useful TSR that you develop using TBONES. That way, I am paid in useful software only if TBONES itself proves genuinely useful to you. ------------------------------------------------------------------------------ T-BONES currently consists of: (1) README: Quick start information. Read this to find out if TBONES might be of use to you. (2) TBONES07.DOC: This complete documentation file. (3) TSRINT.ASM: Assembly Language skeletal program for use in developing a TSR program that is triggered into action by "Hooking" to a user-specified Interrupt. Raw program with NO features to keep you out of trouble with DOS nonreentrancy. (4) TSRINT.COM: Executable Hooked Interrupt TSR code obtained by assembling TSRINT.ASM (with MASM), linking (with DOS' LINK), and conversion from .EXE to .COM form using DOS' EXE2BIN. The commands necessary to convert TSRINT.ASM to TSRINT.COM are: MASM TSRINT; LINK TSRINT; (Ignore the No Stack warning) EXE2BIN TSRINT TSRINT.COM Or, if working with Borland's TASM package: TASM /ml TSRINT TLINK /x/t TSRINT (5) TSRKEY.ASM: Assembly Language skeletal program for use in developing a TSR program that is triggered into action by a user-specified "Hot Key" combination. Raw program with NO features to keep you out of trouble with DOS nonreentrancy. (6) TSRKEY.COM: Executable HotKey TSR code obtained by assembling TSRKEY.ASM (with MASM), linking (with DOS' LINK), and conversion from .EXE to .COM form using DOS' EXE2BIN. The commands necessary to convert TSRKEY.ASM to TSRKEY.COM are: MASM TSRKEY.ASM; LINK TSRKEY.OBJ; EXE2BIN TSRKEY.EXE TSRKEY.COM Or, if working with Borland's TASM package: TASM /ml TSRKEY TLINK /x/t TSRKEY (7) TSRBONES.ASM: TSRBONES is the flagship program in this package. It is an Assembly Language skeletal program for use in developing a TSR program that is triggered into action by a user-specified "Hot Key" combination WHEN DOS IS AT "BUSY IDLE" Int 28h. When DOS is at "Busy Idle", it is safe to use DOS Function calls ABOVE 0Ch without incurring problems with DOS' non-reentrancy. The code also prevents multiple installations. The TSR also will not trigger if the CPU is busy servicing a hardware interrupt (IRQ0 - IRQ7). (8) TSRBONES.COM: Executable HotKey "DOS-OK" TSR code obtained by assembling TSRBONES.ASM (with MASM), linking (with DOS' LINK), and conversion from .EXE to .COM form using DOS' EXE2BIN. The commands necessary to convert TSRBONES.ASM to TSRBONES.COM are: MASM TSRBONES.ASM; LINK TSRBONES.OBJ; EXE2BIN TSRBONES TSRBONES.COM Or, if working with Borland's TASM package: TASM /ml TSRBONES TLINK /x/t TSRBONES (9) HISTORY: The revision history for the TBONES package. ****************************************************************************** ASSEMBLERS: The following assemblers are known to successfully assemble the ASM files in TBONES: - ARROWSOFT Public Domain Assembler v1.00d (64K Model) - MASM v1.0 and v4.00 - TASM v1.00 ****************************************************************************** TSR .COM FILES: TSRINT: ------ TSRINT, as distributed, hooks to Interrupt 05h, which is triggered by the Print Screen Key. The routine included in the distributed code for TSRINT simply rings the terminal Bell signal whenever Int 05h is executed, i.e, whenever the Print Screen key is pressed. You, of course, will replace or expand upon this simple routine so that your TSR performs your desired function. TSRKEY: ------ TSRKEY, as distributed, is set to trigger on CTRL-ALT-K as a Hot Key combination. The routine included in the distributed code for TSRKEY simply rings the terminal Bell signal whenever the CTRL and ALT keys are held down and then the "K" key depressed. You, of course, will replace or expand upon this simple routine so that your TSR performs your desired function in response to your specified Hot Key combination. TSRBONES: -------- TSRBONES, as distributed, is set to trigger on CTRL-ALT-B as a Hot Key combination. The routine included in the distributed code for TSRBONES simply rings the terminal Bell signal whenever the CTRL and ALT keys are held down and then the "B" key depressed AND either the InDOS Flag is zero OR DOS is at "Busy Idle" (Int28h) AND no hardware interrupt (IRQ0 - IRQ7) is being serviced. In addition, the TSR is not allowed to trigger if DOS is handling a Critical Error, or if a disk access is underway (i.e., if INT 13h is active). Furthermore, the code for TSRBONES detects prior installation and does not permit multiple installations of the TSR. You, of course, will replace or expand upon the simple Bell ringing routine so that your TSR performs your desired function in response to your specified Hot Key combination. **************************************************************************** NOTES ON T-BONES: ---------------- - Learning how TSRs work: In learning to program TSRs, I have written these programs in the order: TSRINT, TSRKEY, several programs leading to TSRBONES. This is the order of increasing capability and complexity. I believe that a study of the source programs in that order might help you in your own quest to learn how TSRs work. TSRBONES is the flagship program of the TBONES package. It incorporates all the tricks I CURRENTLY KNOW about in making a TSR coexist safely and robust- ly with DOS and with other TSRs. If you detect important oversights on my part about these complex matters, I would appreciate your telling me. If you know that your TSR is simple enough that DOS reentrancy is not of concern, you might decide to use the very RAW frameworks of TSRINT or TSRKEY, for triggering on an Interrupt or on a Hot Key respectively. You might then decide to enhance them by incorporating one or more desired features out of the TSRBONES source code. If you want maximum bells-and-whistles, robustness, and protection for your TSR from problems with DOS reentrancy and interference with other CPU tasks, use TSRBONES. TSRBONES requires only about 240 more resident bytes than the simple TSRKEY. You may well view that as a small price to pay for the safer, more robust, and capable code of TSRBONES. I might add that I do not pretend that my own knowledge of TSRs (or of Assembly Language) is yet complete, and I would appreciate any comments you might send to me via E-mail on problems or bugs or bad practice that you detect in the included code. - Protecting against problems with DOS non-reentrancy: Be aware that the simple skeletal programs, TSRINT and TSRKEY, in T-BONES do NOTHING to protect you from problems caused by DOS' non-reentrancy. Basically, this means that if your TSR interrupts your processor while it is executing code that DOS provides to perform some function, then you SHOULD NOT PROGRAM YOUR TSR TO RE-ENTER ANY CODE PROVIDED BY DOS. If your processor WERE to re-enter DOS code, it might modify memory locations used by DOS and therefore when your TSR is exited and the processor attempts to pick up where it left off in the DOS code it was executing when your TSR interrupted it, unpredictable (and even disastrous) effects can result. These guidelines can help keep you out of trouble if you use TSRINT or TSRKEY: 1. Don't use DOS functions ( accessed via Int 21h ) unless you HAVE to. 2. If you MUST use DOS functions read a good DOS programming reference and study the code in TSRBONES.ASM to learn more about the following techniques: a) Monitoring the InDOS flag to see when it is safe to call a DOS function. See the description of Function 34h of Int 21h in a DOS programming reference to learn how to monitor this flag. b) Monitoring the Critical Error flag. This flag can keep you out of trouble with DOS in some cases when InDOS erroneously indicates OK to enter DOS. c) Monitoring Int 28h to detect DOS' "Busy Wait" for console I/O. It is safe to enter DOS for anything except console I/O when DOS is in a "Busy Wait". Even though the InDOS flag will indicate the processor is in DOS code when this "Busy Wait" is occurring, Int 28h can be used to give the OK to make non-console-I/O DOS calls (Int21h Functions above 0Ch). d) Hooking BIOS Int13h to keep track of when time-critical disk access is occurring so your TSR does not intrude. - No check for prior installation in TSRINT and TSRKEY: A shortcoming of the raw programs, TSRINT and TSRKEY, is that those TSRs don't check for prior installations of themselves. Thus, they depend upon you not to waste memory in installing them multiple times. ***************************************************************************** SOURCES OF FURTHER INFORMATION ON PROGRAMMING TSRs: BOOKS: ----- One of the best treatments I know of on the complex considerations in writing a robust TSR appears in: _Inside DOS: A Programmer's Guide_ Author: Michael J. Young Publisher: SYBEX, 490 pp., (C)1988, 1990. Chapter 11: "Memory Residency" pp. 321-360. A book which contains a wealth of information useful in designing good TSRs is: _Undocumented DOS: A Programmer's Guide to Reserved MS-DOS Functions and Data Structures_ by Andrew Schulman, Raymond J. Michels, Jim Kyle, Tim Paterson, David Maxey, and Ralf Brown. Publisher: Addison-Wesley Publishing Company, Inc., (C)1990. Chapter 5: "Memory Resident Software: Pop-ups and Multitasking" by Michels, Paterson, and Schulman. I also have learned much from the book: _DOS Programmer's Reference, 2nd Edition_ by Terry Dettmann and revised for 2nd Edition by Jim Kyle (C)1989 by QUE Corporation, Programming Series I have found it indispensable as a source for detailed DOS programming information. The Waite Group's _Microsoft Macro Assembler Bible_ by Nabaiyoti Barkakati has been most useful on Assembly Language matters. RALF BROWN'S INTERRUPT LIST: --------------------------- Ralf Brown maintains an astounding file which is chock-full of detailed, absolutely-indispensable information for DOS programmers on Hardware, BIOS, DOS, and other interrupts. This file is available free for the downloading from many BBS's, as well as via anonymous ftp from most major archival sites on the Internet. You should not be without this file, which is widely-known as "Ralf Brown's Interrupt List". Ask about it. You will find it. As of this writing, INTER191.ZIP is the most recent version. In general, INTERxyy.ZIP is release x of year yy. TSRDEMO2: -------- TSRDEMO2 by Thomas Brandenborg of Denmark provides valuable data to anyone learning to safely program TSRs. His .ASM source program is a "sample demonstration of a safe approach for writing TSR programmes." This program is available on Compuserve Forums, as well as on many BBSs. Mr. Brandenborg might be reached at: Thomas Brandenborg Lundbyesgade 11 DK-8000 Aarhus C DENMARK TesSeRact(TM): ------------- A lot of helpful information in developing TSRs which overcome the shortcomings above, and others, can be obtained from the TesSeRact(TM) development team. This group provides data on how to produce TSRs compliant with the TesSeRact standards. These standards are intended to make TSRs peacefully coexist with DOS and with each other in a bullet-proof, safe, robust manner. You can learn much from this team that you will need to know in programming complex TSRs. For information about TesSeRact, contact the TesSeRact Development Team at: TesSeRact Development Team c/o Chip Rabinowitz 2084 Woodlawn Avenue Glenside, PA 19038 1-215-884-3373 Compuserve: 70731,20 MCIMAIL: 315-5415 This MCIMAIL Account has been provided to the TesSeRact Development Team by Borland International, Inc. The TesSeRact Development Team is in no way associated with Borland International, Inc. TesSeRact is a trademark of the TesSeRact Development Team. ***************************************************************************** KNOWN BUGS: ---------- None. (Now just how long might THAT last? :-) -END-